home *** CD-ROM | disk | FTP | other *** search
/ Micro R&D 5: Mand 2000 / Mand 2000 - Micro R&D CD-ROM Vol 5.iso / documentation / mand2000tech.doc < prev    next >
Text File  |  1994-10-20  |  10KB  |  221 lines
  1.  
  2.      Mand2000 Technical Information - Copyright © 1993 Cygnus Software
  3.      Please do not distribute.
  4.  
  5.                                File Formats
  6.  
  7.     In addition to the regular IFF chunks, such as ILBM, BODY, CMAP, CAMG,
  8. CRNG, CCRT and GRAB, Mand2000 saves some additional custom chunks, to store
  9. such  things  as the fractal location, julia seed, colour mapping settings,
  10. and  iteration  information.  To facilitate the writing of support programs
  11. for  Mand2000,  all  of  the  custom  chunks are documented here, with some
  12. sample source code.
  13.  
  14.  
  15.  
  16.                              Standard Chunks:
  17.  
  18.     First,  some  information about how Mand2000 uses the standard chunks.
  19. In  the ILBM chunk, the page width and page height that Mand2000 writes are
  20. the  size of the screen, and the w and h fields are the width and height of
  21. the drawing area of that window.  Page width and page height will always be
  22. equal  or  greater  than  w  and  h.   When  loading,  Mand2000 attempts to
  23. interpret page width and page height in the same way.
  24.  
  25.     The  GRAB  chunk is used to store the pixel location that was used for
  26. the  last  zoom in.  This information is ignored by Mand2000 but is crucial
  27. to  the  TweenPlayer  as  it tells it what point to zoom in on when playing
  28. back  a  tween  movie.  If these chunks are lost then the tween movies will
  29. not  play  back properly.  Tween movie playing of arbitrary pictures can be
  30. done by adding GRAB chunks to the files with appropriate x,y coordinates.
  31.  
  32.  
  33.  
  34.                               Custom Chunks:
  35.  
  36.     The  most important chunks are the location chunks.  These specify the
  37. coordinates  of  the  left, top, right and bottom edges of the saved image.
  38. The  demo  version of Mand2000 never saves these chunks, but the production
  39. version  always  does,  except  when  you save a palette or a screen.  This
  40. information  is  always  stored  twice,  in two separate chunks.  The first
  41. chunk is the same one used in MandelMania, thus insuring file compatibility
  42. with  that program.  Mand2000 also reads Mandelblitz and TurboMandel custom
  43. chunks but does not write them.  Reading and writing of more custom fractal
  44. chunks  would  have  been  provided  if  the  authors of these programs had
  45. documented  their  chunks.
  46.  
  47.     The  following  information  has  been  extracted from the MandelMania
  48. documentation.  Thanks to Markus for making this information available.
  49.  
  50. > To store specific picture parameters, a special chunks are built in.  The
  51. > most important one called "MAND".  The structure of this chunk is as follows:
  52. > 
  53. > struct MAND_Chunk {
  54. >     USHORT LeftEdge,TopEdge,Width,Height;  /* windowcoordinates */
  55. >     long double xleft,xright,ybottom,ytop; /* range */
  56. >     long double xconst,yconst;             /* Julia constant */
  57. >     ULONG Iterations;                      /* max number of Iterations */
  58. >     ULONG Type;                            /* Type, see below */
  59. > };
  60. > 
  61. > Remember that a 'long double' is 12 Bytes (=96 bits) long.
  62. > 
  63. > Mand_Chunk->Type can be one of the following:
  64. > 
  65. > #define TYPE_MANDELBROT 0
  66. > #define TYPE_JULIA 1
  67.  
  68.     The  MandelMania  chunk is probably the easiest one to use because the
  69. numbers  are  stored as simple long doubles that your compiler understands.
  70. However  this  format  does  have  finite accuracy.  At magnifications much
  71. beyond  approximately  one  thousand  million  million  long doubles are no
  72. longer  sufficient.   This may seem like a lot, and often is, but sometimes
  73. zooming  beyond that is nice, and Mand2000 does support it, which is why we
  74. have the FXPL, FXL2, FXPJ and FXJ2 chunks.  FXPL and FXL2 store the fractal
  75. location,  and  FXPJ and FXJ2 store the julia seed location, if applicable.
  76. The reason that there are two formats for each of these purposes is because
  77. the  FXPL  and  FXPJ  formats, which were initially used by MandFXP in 1986
  78. (also  by  CygnusSoft) didn't allow for storing of coordinates greater than
  79. +-3.99.  Since Mand2000 allows zooming way out, as well as way in, the FXL2
  80. and  FXJ2  chunks  were  defined.  FXPL and FXL2 are never used at the same
  81. time,  similarly  FXPJ  and  FXJ2  are never used at the same time - a good
  82. reader  will check for both, but FXL2 and FXJ2 are only used if the fractal
  83. has  been zoomed out.  Before explaining the chunks further I'll give the C
  84. language declarations for them.
  85.  
  86. #define    NUMLONGS            36
  87.  
  88. #define    NUMCOORDINATES        4    /* Left, right, top and bottom. */
  89.  
  90. #define    NUMJULCOORDINATES    2    /* JuliaX, JuliaY */
  91.  
  92. /* Size equals sizeof(UWORD) + PRECISION * sizeof(short) * NUMCOORDINATES. */
  93.  
  94. struct LocationData
  95.     {
  96.     UWORD CurrentPrecision;
  97.     short    coordinates[NUMLONGS*2*NUMCOORDINATES];
  98.     };
  99.  
  100. struct JuliaPointData
  101.     {
  102.     UWORD CurrentPrecision;
  103.     short    coordinates[NUMLONGS*2*NUMJULCOORDINATES];
  104.     };
  105.  
  106.     Because Mand2000 can zoom in extremely far, these structure need to be
  107. able to hold extremely precise numbers.  The current maximum accuracy is 36
  108. long  words, or 144 bytes per number.  Since it would be rather inefficient
  109. to  store  the  entire  144  bytes  per number when it wasn't all used, the
  110. CurrentPrecision field specifies how many words of data are stored for each
  111. coordinate.    Typically  CurrentPrecision  is  equal  to  the  calculation
  112. accuracy  plus  one.  The number of words stored in a LocationData chunk is
  113. equal  to CurrentPrecision times four plus one.  The number of words stored
  114. in  a JuliaData chunk is equal to CurrentPrecision times two plus one.  The
  115. coordinates  in the FXPL chunk are stored in the order left, right, top and
  116. then  bottom.   The  coordinates  in the FXPJ chunk are stored in the order
  117. juliax, juliay.
  118.  
  119.     The  numbers are stored as fixed point numbers, with the decimal point
  120. stored  after  the  third  bit.   They are stored in standard Motorola twos
  121. complement  format  (normal binary number format), as a stream of bits with
  122. the   highest   precision   bits   coming   first.    As   an  example,  if
  123. CurrentPrecision was two, and the location was -3.0,+3.0,+2.0,-2.0, a total
  124. of nine words would be written out to the FXPL chunk as follows:
  125.  
  126. 0x0002 = number of words per number 
  127. 0xA000 = left = -3.0 with the decimal point after the third bit.
  128. 0x0000 = the rest of left.
  129. 0x6000 = right = 3.0 with the decimal point after the third bit.
  130. 0x0000 = the rest of right.
  131. 0x4000 = top = 2.0 with the decimal point after the third bit.
  132. 0x0000 = the rest of top.
  133. 0xC000 = bottom = -2.0 with the decimal point after the third bit.
  134. 0x0000 = the rest of bottom.
  135.  
  136.     The  data  format of the FXL2 and FXJ2 structures is identical, except
  137. that  instead  of  there  being three bits to the left of the decimal point
  138. there are nineteen bits to the left, in other words there is one additional
  139. word  of  data  to  the  left of the decimal point.  CurrentPrecision still
  140. contains  the  number of words stored per number and the formulas above for
  141. calculating  chunk size still hold, however the numbers stored can be 65536
  142. times larger, allowing zooming out well beyond the interesting areas of the
  143. fractals.   The  additional binary digits to the left should be ones if the
  144. number is negative, zeroes if the number is positive.
  145.  
  146.  
  147.  
  148.     Some more miscellaneous information is stored in the FXD2 chunk.  The
  149. structure of this chunk is as follows:
  150.  
  151. struct OtherFractalData
  152.     {
  153.     short    Size;    /* NEVER load more than you know how to deal with. */
  154.                     /* NEVER load more than the structure contains. */
  155.     short    VersionNumber;    /* Currently always zero. */
  156.  
  157.     short    actualmaxiter;    /* Maximu iterations. */
  158.     short    numpasses;    /* Zero to three. */
  159.     short    mindrawcolour;    /* Purely advisory - first colour to draw with. */
  160.     long    morphfactor;        /* 0-32768, translated to 32768-0 on load so that 0 maps to 1.0 instead of 0.0 */
  161.                         /* Stored with an extra word of precision for accurate continuance of morphs. */
  162.                         /* The extra word might not be used. */
  163.     short    colourmaptype;    /* 0 is the old fashioned linear wrap-around type. */
  164.     short    colourmapskip;    /* This is taken straight from the colour map */
  165.                         /* requester, as are colourmaptype and colourmap */
  166.                         /* offset. */
  167.     short    fractaltype;    /* A number from zero to five (currently).  Odd */
  168.                         /* numbers represent julia sets, even numbers */
  169.                         /* are Mandelbrot (0), Mandcubed (2) and */
  170.                         /* Mand fourth (4). */
  171.     short    colourmapoffset;
  172.     };
  173.  
  174.  
  175.  
  176.     If you save a Mand2000 picture when it hasn't finished calculating, an
  177. additional  chunk is saved called the continue chunk, FXCO.  This structure
  178. is   mostly  private  to  Mand2000,  but  it  is  listed  here  anyway  for
  179. completeness.
  180.  
  181. struct restartinfo
  182.     {
  183.     BOOL    picturedone;    /* Always false if this structure is written. */
  184.  
  185.     short    levelstarted;    /* Zero to three. */
  186.  
  187.     short    level, currentx, currenty, currenttopy, currentbottomy;
  188.     short    blocksize, xskip;    /* Current pixel size - 1,2,4 or 8. */
  189.                             /* Jump distance - either blocksize */
  190.                             /* or blocksize*2. */
  191.  
  192.     short    xgrid, ygrid;        /* Offset of draw grid from top left. */
  193.  
  194.     BOOL    reflecttype;    /* This says whether reflection is allowed, and what type. */
  195.     BOOL    reflecting;    /* This says whether reflection is currently being used. */
  196.     short    zeroline;    /* Line where c.i = 0.  The x-axis.  Only valid if reflecting is set. */
  197.     short    zerocolumn;    /* Line where c.r = 0.  The y-axis.  Only valid if reflecting is set. */
  198.  
  199.     BOOL    fractaltype;    /* zero to five. */
  200.  
  201.     struct region donebox[4];    /* Private - just ignore this data. */
  202.     };
  203.  
  204.  
  205.     With  version  2.0  of  Mand2000,  a  single  CMAP chunk was no longer
  206. sufficient.   When fractals are saved in any of the True Colour modes (HAM,
  207. HAM8  or  dithered true colour) the CMAP palette is used for displaying the
  208. data,  and an additional palette is needed for storing the colours that the
  209. user  edits.   This second palette is stored in a chunk called `FCMP'.  The
  210. format  of  this  chunk is identical to the `CMAP' chunk, and Mand2000 will
  211. always store 256 colours in these chunks.
  212.  
  213.     Finally,  Mand2000  optionally  uses  a  custom chunk called `FITR' to
  214. stored  Fractal ITeRation information.  When the iteration data is saved in
  215. this  chunk,  Mand2000  can  reload  the  file  and  then adjust the colour
  216. mapping,  without  recalculating  anything.  This chunk also allows ADPro's
  217. Fractal2000  loader  to  load Mand2000 pictures in as 24 bit images.  There
  218. are  many  other  applications for the iteration data in this hunk.  If you
  219. are   interested   in  writing  a  program  that  uses  Mand2000  iteration
  220. information, please contact us for information on the chunk format.
  221.